0.3.0: declare once, call directly — the definition module - #4

What

0.3.0: the definition module. Declare each capability once and call it directly inside the handler:

const Charge = defineActivity("charge", { payload: { orderId: Schema.String }, success: Schema.String });
const Approval = defineDeferred("order/approval", { success: Schema.String });

const OrderLive = OrderFlow.toLayer((payload) =>
  Effect.gen(function* () {
    const receipt = yield* Charge({ orderId: payload.orderId });
    const approver = yield* Approval.await;
    return `${receipt}:by:${approver}`;
  }),
);

Every primitive requires exactly one service, WorkflowOps — the seam an engine implements. workflowBundle provides the Temporal runtime; the new makeTestWorkflowOps (testing module) provides an in-memory one, so the same handler function runs on real Temporal or in a plain unit test with no engine, no sandbox, no server. Handlers import nothing engine-shaped — which is the answer to the "TypedActivity feels like an engine leak" feedback.

Also in the module: version(site, names) (patch-marker logic branches) and evolved(current, legacy, migrate) (newest-first schema evolution with pure migrations). Client-side driving addresses the declaration's underlying primitive: U.update, M.mailbox, C.cell, D.deferred.

How it works

Declarations wrap the existing primitives (TypedActivity, DurableMailbox, DurableUpdate, StateCell, upstream DurableDeferred) and type each operation against the WorkflowOps context service. The seam (WorkflowOpsRuntime) is one operation per primitive kind over unknown; each define* narrows it exactly once, against the schemas the same declaration carries. workflowBundle provides the Temporal implementation to hosted layers during registration; the per-run wrapper supplies the sandbox services the ops dispatch into. Wire identity stays the explicit name string, so refactors never change the wire.

Migration

The whole repo authors with define*: 16 test fixtures, both examples, all docs (new "Declaring capabilities" guide page), README, EXAMPLES.md. The versioning-chain fixtures deliberately stay on raw Activity.make — they prove replay compatibility with byte-identical commands across code generations, and the full replay drill passes unchanged, which doubles as proof the new plumbing does not alter recorded histories. Low-level per-primitive calls (callActivity, takeMailbox, ...) remain exported from engine-sandbox as the machinery underneath, undocumented as authoring surface.

Audit (second commit)

A dedicated bug/type-honesty audit ran before this PR; its findings are the second commit:

• eraseR replaces the as never casts on the Temporal ops runtime — only the R channel is erased; success/error shapes stay compile-checked against the seam. UpdateRequest unified to one shape. temporalWorkflowOps made module-private (outside the per-run wrapper it would die at call time).
• WorkflowOpsRuntime.version is generic over the names tuple: three casts deleted, both engines implement it verbatim.
• The memory runtime round-trips every channel through the declaration's wire codec (activity payload/success/error, mailbox and update payloads, update responses, state values, deferred completions) — schema-invalid values defect in unit tests exactly as they would on Temporal. Responding twice to one update dies, mirroring the engine.
• The versioning-on-main-fiber lint rule now covers definition-only handler modules via their version import (alias-aware); the old import gate made the new detection dead for exactly those files.

Validation

• typecheck, lint, build, docs build (dead links checked): clean
• full suite: 24 files / 63 tests green, incl. the new definition.test.ts (same handler on memory + real Temporal, typed update refusal, typed activity failure) and schema-evolution.test.ts
• both examples run end-to-end on the new surface
• versioning-chain replay drill green (histories unchanged)